UVC: move application decision to the application #93192

josuah · 2025-07-16T10:22:26Z

Dependency:

uvc: improve standard compliance and MacOS compat #92320

The USB class was doing arbitrary "best guess" choices about what pixel formats or resolutions to include (all of them, and min/max only when format are ranges).

In the class, add a uvc_add_format() to allow the application to push the exact format it wants
In the class, remove all format-related video API calls away from the UVC stack, to let the application handle this
In the sample, filter out formats that are not supported by the host whenever standard formats are also supported
In the sample, filter out formats that are too large for the memory

What is added in the sample is a matter of application choices, and trapping these choices in the UVC class prevented the samples to work without manual configuration on diverse platform.

MacOS support still not confirmed.
Linux, Windows, Android tested functional with the hardware I have.

josuah · 2025-07-16T10:27:41Z

This is not ready for review, will be properly split in individual commits, and "un-drafted" when ready...

josuah · 2025-07-18T21:56:06Z

Force-push:

Rebase on top of the MacOSX-related bugfix

Windows, Linux, MacOSX, Android are now expected to all work.

Tested with nRF52840-DK:

west build --board=nrf52840dk/nrf52840 --snippet=video-sw-generator samples/subsys/usb/uvc/

Tested with Arduino Nicla Vision:

west build --board=arduino_nicla_vision/stm32h747xx/m7 samples/subsys/usb/uvc/

josuah · 2025-07-24T16:25:00Z

Force-push:

Rebase on main to fix conflict.
Reword the documentation and commit messages.
Add a migration guide entry for the semantic change (but no direct API breakage).

sonarqubecloud · 2025-07-24T16:54:30Z

Quality Gate passed

Issues
2 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

tmon-nordic

Needs rebase.

josuah · 2025-10-11T20:13:49Z

Force-push:

Apply review suggestions
Check compliance script typo errors

avolmat-st

LGTM, thanks a lot !!

avolmat-st · 2025-10-13T06:37:52Z

@jfischer-no, @tmon-nordic, could you have a look at this PR which is a dependency for some others ? Thanks.

jfischer-no · 2025-10-13T11:29:12Z

include/zephyr/usb/class/usbd_uvc.h

- * At runtime, it will forward all USB controls from the host to this device.
+ * It will query its supported video controls and frame intervals and use this information to
+ * generate the USB descriptors presented to the host. At runtime, it will forward all USB controls
+ * from the host to this device.


At runtime, it will forward all USB controls from the host to this device.

How would this function "forward all USB controls" and why? I doubt this documentation is correct. Perhaps it needs different wording, also not clear how the changes are relevant to the commit message.

What I meant was that the class would turn USB control commands for the UVC class into "video controls" at the Zephyr Video API level.

Good opportunity to improve the inaccurate documentation.

I realized that I did integrate @avolmat-st suggestions into existing commits, I just split them out like I should have.

ngphibang

Just some nits, otherwise LGTM.

ngphibang · 2025-10-14T19:05:20Z

samples/subsys/usb/uvc/src/main.c

+/* Format capabilities of video_dev, used everywhere through the sample */
+static struct video_caps video_caps = {.type = VIDEO_BUF_TYPE_OUTPUT};
+
+static void app_add_format(uint32_t pixfmt, uint16_t width, uint16_t height)


width and height parameters should be uint32_t as in video_format structure. The calls to this function (line 57 and 60) also passes uint32_t type from video_format_caps

Actually, I see uint16_t is OK as well, uint32_t is a bit overkill. Maybe we should change the video_format_caps and video_format 's width / height fields to uint16_t in the future ?

I must have been too used to UVC sizes... Done.

ngphibang · 2025-10-14T19:11:24Z

samples/subsys/usb/uvc/src/main.c

+	};
+	int ret;
+
+	/* Set the format to get the pitch */


Should be /* Set the format to get the size */ ?

Yes, the comment was not updated since fmt.size introduction. Done.

ngphibang · 2025-10-14T19:12:42Z

samples/subsys/usb/uvc/src/main.c

+	/* Set the format to get the pitch */
+	ret = video_set_format(video_dev, &fmt);
+	if (ret != 0) {
+		LOG_ERR("Could not set the format of %s", video_dev->name);


Should also log the fmt (size, width, height) to give more info about which format has failed ?

Good idea. Done.

ngphibang · 2025-10-14T19:15:46Z

include/zephyr/usb/class/usbd_uvc.h

 void uvc_set_video_dev(const struct device *uvc_dev, const struct device *video_dev);

+/**
+ * @brief Set the video format capabilities that a UVC instance will present to the host.


The function description is confused to me. The function rather add a format, not set the video format caps, right ?

@brief Add a video format ...

Yes, this got refactored and the comment did not get updated properly. Done.

ngphibang · 2025-10-14T19:16:20Z

include/zephyr/usb/class/usbd_uvc.h

+ * @param uvc_dev The UVC device to configure
+ * @param fmt The video format to add to this UVC instance


@param Pointer to ...

Done here too.

ngphibang · 2025-10-14T19:16:52Z

include/zephyr/usb/class/usbd_uvc.h

 *
 * @param uvc_dev The UVC device
- * @param video_dev The video device that this UVC instance controls
+ * @param video_dev The video device that this UVC instance send controls requests to


@param Pointer to ...

Updated here and other places.

ngphibang · 2025-10-14T19:23:28Z

samples/subsys/usb/uvc/src/main.c

+
+	ret = video_set_format(video_dev, &fmt);
+	if (ret != 0) {
+		LOG_WRN("Could not set the format of %s", video_dev->name);


Should also log the fmt (size, width, height) to give more info about which format has failed ?

Done here too.

ngphibang · 2025-10-14T19:32:29Z

samples/subsys/usb/uvc/src/main.c

 static struct video_caps video_caps = {.type = VIDEO_BUF_TYPE_OUTPUT};

-static void app_add_format(uint32_t pixfmt, uint16_t width, uint16_t height)
+static bool app_is_standard_format(uint32_t pixfmt)


nit: app_is_supported_format() ? as the definition of which formats are "standard" seems not clear

This was the UVC standard
USB_Video_Payload_Uncompressed_1.5.pdf

But the list is already outdated and incomplete!
I added NV12.

I removed GREY, added NV12, and renamed the function.

Glad to pick a different strategy!

ngphibang · 2025-10-14T19:33:02Z

samples/subsys/usb/uvc/src/main.c

+}
+
+/* Check whether the video device supports one of the wisespread image sensor formats */
+static bool app_has_standard_formats(void)


nit : app_has_supported_formats() ?

Applied there too.

For supporting situations where UVC formats are dynamically generated at runtime, do not return an error in case descriptors were not added, but instead verbosely log the error and allow enumeration to happen. Signed-off-by: Josuah Demangeon <[email protected]>

Make use of the recently merged fmt->size to know the maximum size of the frame to be allocated, which works for both compressed and uncompressed video. Signed-off-by: Josuah Demangeon <[email protected]>

The UVC class was deciding itself which formats were sent to the host. Remove this logic out of the UVC class and introduce uvc_add_format() to give the application the freedom of which format to list. Signed-off-by: Josuah Demangeon <[email protected]>

The UVC class now lets the application select the format list sent to the host. Leverage this in the sample to filter out any format that is not expected to work (buffer too big, rarely supported formats). Signed-off-by: Josuah Demangeon <[email protected]>

Add USB UVC device's new uvc_add_format() function to the release note, and document the semantic changes of UVC APIs in the migration guide. Signed-off-by: Josuah Demangeon <[email protected]>

josuah

Force-push:

Rebased on main
Applied @ngphibang suggestions

josuah · 2025-10-14T20:23:51Z

samples/subsys/usb/uvc/src/main.c

+/* Format capabilities of video_dev, used everywhere through the sample */
+static struct video_caps video_caps = {.type = VIDEO_BUF_TYPE_OUTPUT};
+
+static void app_add_format(uint32_t pixfmt, uint16_t width, uint16_t height)


I must have been too used to UVC sizes... Done.

josuah · 2025-10-14T20:25:02Z

samples/subsys/usb/uvc/src/main.c

+	};
+	int ret;
+
+	/* Set the format to get the pitch */


Yes, the comment was not updated since fmt.size introduction. Done.

josuah · 2025-10-14T20:25:11Z

samples/subsys/usb/uvc/src/main.c

+	/* Set the format to get the pitch */
+	ret = video_set_format(video_dev, &fmt);
+	if (ret != 0) {
+		LOG_ERR("Could not set the format of %s", video_dev->name);


Good idea. Done.

josuah · 2025-10-14T20:26:52Z

samples/subsys/usb/uvc/src/main.c

+
+	ret = video_set_format(video_dev, &fmt);
+	if (ret != 0) {
+		LOG_WRN("Could not set the format of %s", video_dev->name);


Done here too.

josuah · 2025-10-14T20:28:12Z

include/zephyr/usb/class/usbd_uvc.h

 void uvc_set_video_dev(const struct device *uvc_dev, const struct device *video_dev);

+/**
+ * @brief Set the video format capabilities that a UVC instance will present to the host.


Yes, this got refactored and the comment did not get updated properly. Done.

josuah · 2025-10-14T20:33:34Z

include/zephyr/usb/class/usbd_uvc.h

 *
 * @param uvc_dev The UVC device
- * @param video_dev The video device that this UVC instance controls
+ * @param video_dev The video device that this UVC instance send controls requests to


Updated here and other places.

josuah · 2025-10-14T20:33:42Z

include/zephyr/usb/class/usbd_uvc.h

+ * @param uvc_dev The UVC device to configure
+ * @param fmt The video format to add to this UVC instance


Done here too.

josuah · 2025-10-14T20:37:51Z

samples/subsys/usb/uvc/src/main.c

 static struct video_caps video_caps = {.type = VIDEO_BUF_TYPE_OUTPUT};

-static void app_add_format(uint32_t pixfmt, uint16_t width, uint16_t height)
+static bool app_is_standard_format(uint32_t pixfmt)


This was the UVC standard
USB_Video_Payload_Uncompressed_1.5.pdf

But the list is already outdated and incomplete!
I added NV12.

josuah · 2025-10-14T20:47:35Z

samples/subsys/usb/uvc/src/main.c

 static struct video_caps video_caps = {.type = VIDEO_BUF_TYPE_OUTPUT};

-static void app_add_format(uint32_t pixfmt, uint16_t width, uint16_t height)
+static bool app_is_standard_format(uint32_t pixfmt)


I removed GREY, added NV12, and renamed the function.

Glad to pick a different strategy!

josuah · 2025-10-14T20:47:42Z

samples/subsys/usb/uvc/src/main.c

+}
+
+/* Check whether the video device supports one of the wisespread image sensor formats */
+static bool app_has_standard_formats(void)


Applied there too.

josuah

.

sonarqubecloud · 2025-10-14T21:25:54Z

Quality Gate passed

Issues
2 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

josuah marked this pull request as draft July 16, 2025 10:22

github-actions bot added area: USB Universal Serial Bus area: Samples Samples labels Jul 16, 2025

github-actions bot requested a review from nashif July 16, 2025 10:23

github-actions bot assigned jfischer-no Jul 16, 2025

zephyrbot requested review from jfischer-no, kartben and tmon-nordic July 17, 2025 02:53

josuah force-pushed the pr_uvc_no_policy branch from 70ab814 to 4833717 Compare July 18, 2025 21:48

josuah changed the title ~~[WIP] UVC: remove the policies from the class~~ UVC: remove the policies from the class Jul 18, 2025

josuah mentioned this pull request Jul 18, 2025

uvc: improve standard compliance and MacOS compat #92320

Merged

josuah added area: Video Video subsystem Release Notes Required Release notes required for this change labels Jul 18, 2025

josuah changed the title ~~UVC: remove the policies from the class~~ UVC: move application decision to the application Jul 19, 2025

josuah force-pushed the pr_uvc_no_policy branch 3 times, most recently from f1cb80e to f5328dd Compare July 24, 2025 16:23

josuah marked this pull request as ready for review July 24, 2025 16:56

zephyrbot added the Release Notes To be mentioned in the release notes label Jul 24, 2025

zephyrbot requested review from cfriedt and jhedberg July 24, 2025 16:57

josuah requested review from avolmat-st, loicpoulain and ngphibang August 14, 2025 19:59

avolmat-st mentioned this pull request Aug 15, 2025

Allow STM32 DCMIPP to work with UVC sample #94562

Open

tmon-nordic previously approved these changes Sep 15, 2025

View reviewed changes

josuah force-pushed the pr_uvc_no_policy branch from 2630948 to 9180180 Compare October 11, 2025 18:58

josuah force-pushed the pr_uvc_no_policy branch from 9180180 to ee542de Compare October 11, 2025 20:13

josuah requested a review from avolmat-st October 11, 2025 20:14

avolmat-st previously approved these changes Oct 12, 2025

View reviewed changes

avolmat-st mentioned this pull request Oct 12, 2025

[RFC] UVC Video encoder (zephyr,videoenc) support #97425

Open

jfischer-no requested changes Oct 13, 2025

View reviewed changes

avolmat-st added this to the 4.3 milestone Oct 13, 2025

josuah dismissed avolmat-st’s stale review via 915e75b October 13, 2025 19:02

josuah force-pushed the pr_uvc_no_policy branch from ee542de to 915e75b Compare October 13, 2025 19:02

josuah requested review from avolmat-st and jfischer-no October 13, 2025 19:15

avolmat-st previously approved these changes Oct 13, 2025

View reviewed changes

mathieuchopstm modified the milestones: 4.3, v4.3.0 Oct 14, 2025

ngphibang reviewed Oct 14, 2025

View reviewed changes

josuah added 2 commits October 14, 2025 20:11

usb: device_next: uvc: use fmt->size instead of computing it everytime

91586bf

Make use of the recently merged fmt->size to know the maximum size of the frame to be allocated, which works for both compressed and uncompressed video. Signed-off-by: Josuah Demangeon <[email protected]>

josuah force-pushed the pr_uvc_no_policy branch from 915e75b to 104a3f6 Compare October 14, 2025 20:18

josuah added 3 commits October 14, 2025 20:38

doc: release: 4.3: add UVC changes

95cc035

Add USB UVC device's new uvc_add_format() function to the release note, and document the semantic changes of UVC APIs in the migration guide. Signed-off-by: Josuah Demangeon <[email protected]>

josuah dismissed avolmat-st’s stale review via 95cc035 October 14, 2025 20:59

josuah force-pushed the pr_uvc_no_policy branch from 104a3f6 to 95cc035 Compare October 14, 2025 20:59

josuah requested a review from avolmat-st October 14, 2025 20:59

josuah commented Oct 14, 2025

View reviewed changes

josuah requested a review from ngphibang October 14, 2025 21:02

		* @param uvc_dev The UVC device to configure
		* @param fmt The video format to add to this UVC instance

UVC: move application decision to the application #93192

Are you sure you want to change the base?

UVC: move application decision to the application #93192

Conversation

josuah commented Jul 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

josuah commented Jul 16, 2025

Uh oh!

josuah commented Jul 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

josuah commented Jul 24, 2025

Uh oh!

sonarqubecloud bot commented Jul 24, 2025

Quality Gate passed

Uh oh!

tmon-nordic left a comment

Choose a reason for hiding this comment

Uh oh!

josuah commented Oct 11, 2025

Uh oh!

avolmat-st left a comment

Choose a reason for hiding this comment

Uh oh!

avolmat-st commented Oct 13, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ngphibang left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

josuah left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

josuah commented Jul 16, 2025 •

edited

Loading

josuah commented Jul 18, 2025 •

edited

Loading